home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Programming / ARexxGuide / Editors / ARx_HelpSystem.README < prev    next >
Text File  |  1994-03-23  |  4KB  |  90 lines
  1. Help-system macros for ARexxGuide
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. Three example macros for the ARexxGuide help system are included here.
  4. A macro for another editor can be created by following the steps in
  5. the help-system tutorial in the TUTORIAL section of the guide.
  6.  
  7. All editor-specific commands are collected together in one section
  8. so that they can be easily changed for a new editor. The tutorial
  9. explains what each command subroutine does.
  10.  
  11. Pressing the help key when the cursor is positioned on any word or
  12. character with a special meaning in ARexx will bring up an AmigaGuide
  13. window with information about the instruction keyword, function, or
  14. operator character.
  15.  
  16. The library rexxarplib.library may be used with this macro to open a
  17. requester that lists information about a word that is not recognized.
  18.  
  19. rexxarplib.library IS NOT REQUIRED, however. If two comment tokens are
  20. removed from the code, the rexxarplib requester will not be shown.
  21. Instructions for making that alteration are included in the macro.
  22.  
  23. -------------------------------------------------------------------------
  24. SETUP:
  25.  
  26. If you choose to use one of the example macros as-is, you should move
  27. the macro for your editor to the REXX: directory. A macro for the system
  28. editor, Ed 2.0, is included so that anyone can test the macros before
  29. customizing one of them for a new editor.
  30.  
  31. The script ARx_Setup.rexx will set a collection of environmental
  32. variables required by each of the help-system macros. That script should
  33. be run before the macro is used, but if it isn't, the macro will usually
  34. call the setup script to get the information needed.
  35.  
  36. The setup script works best if the library `rexxreqtools.library' is
  37. available. That's part of the distribution for ReqTools by Nico François.
  38. If the library isn't available, other requester options will be tried
  39. before user interaction with simple console windows is used.
  40.  
  41. -------------------------------------------------------------------------
  42. HOW THE HELP SYSTEM WORKS:
  43.  
  44.         In the list below the { ^ } character is used to indicate the
  45.         position of the cursor when the help key is pressed. The notes
  46.         after the { :: } characters explain what the macro will display.
  47.  
  48. -------
  49.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  50.  ^
  51.  :: A requester will present information about the clause. It identifies
  52.     the clause as an instruction, assignment, command, comment, or null.
  53. -------
  54.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  55.                                                  ^
  56.  :: The ARexxGuide node for DO will be displayed. If the cursor is located
  57.     at an end-of-line blank, it will look for a node matching the last
  58.     word in the line. It isn't necessary to enter the () after a function
  59.     name to get help for that function. Just type the name and press help.
  60. -------
  61.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  62.        ^
  63.  :: The ARexxGuide node for the ABBREV() function will appear.
  64. -------
  65.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  66.                   ^
  67.  :: The ARexxGuide node explaining parentheses will appear. Generally,
  68.     when the cursor is located on a punctuation mark of some kind, the
  69.     node for that character will appear. This is useful when one wishes to
  70.     check for valid operator characters.
  71. -------
  72.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  73.                            ^
  74.  :: A requester will identify the current clause as an instruction and
  75.     will identify 'Info' as a variable and as a function argument. If a
  76.     lookup word is not recognized as an instruction keyword or subkeyword
  77.     or as a function name, the macro will attempt to identify how the word
  78.     is used in the clause. It recognizes variables, numbers, strings,
  79.     function names, function arguments, and more. It will, however, be
  80.     confused by a clause that includes multiple levels of quotation marks.
  81. --------
  82.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  83.                                    ^
  84.  :: This would normally be identified in a requester as a string, but
  85.     since SHOW() is the name of a built-in macro, the macro won't make it
  86.     that far. It will display the ARexxGuide node for SHOW(). In general,
  87.     the macro will display the node for any word recognized as a function
  88.     or instruction name, even if the word is used in a different context
  89.     in the clause.
  90.